'\" t
.\"     Title: vfs_fruit
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 10/24/2016
.\"    Manual: System Administration tools
.\"    Source: Samba 4.5
.\"  Language: English
.\"
.TH "VFS_FRUIT" "8" "10/24/2016" "Samba 4\&.5" "System Administration tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
vfs_fruit \- Enhanced OS X and Netatalk interoperability
.SH "SYNOPSIS"
.HP \w'\ 'u
vfs objects = fruit
.SH "DESCRIPTION"
.PP
This VFS module is part of the
\fBsamba\fR(7)
suite\&.
.PP
The
vfs_fruit
module provides enhanced compatibility with Apple SMB clients and interoperability with a Netatalk 3 AFP fileserver\&.
.PP
The module should be stacked with
vfs_catia
if enabling character conversion and must be stacked with
vfs_streams_xattr, see the example section for the correct config\&.
.PP
The module enables alternate data streams (ADS) support for a share, intercepts the OS X special streams "AFP_AfpInfo" and "AFP_Resource" and handles them in a special way\&. All other named streams are deferred to
vfs_streams_xattr
which must be loaded together with
vfs_fruit\&.
.PP
vfs_fruit requires "ea support = yes"\&.
.PP
Be careful when mixing shares with and without vfs_fruit\&. OS X clients negotiate SMB2 AAPL protocol extensions on the first tcon, so mixing shares with and without fruit will globally disable AAPL if the first tcon is without fruit\&.
.PP
Having shares with ADS support enabled for OS X client is worthwhile because it resembles the behaviour of Apple\*(Aqs own SMB server implementation and it avoids certain severe performance degradations caused by Samba\*(Aqs case sensitivity semantics\&.
.PP
The OS X metadata and resource fork stream can be stored in a way compatible with Netatalk 3 by setting
fruit:resource = file
and
fruit:metadata = netatalk\&.
.PP
OS X maps NTFS illegal characters to the Unicode private range in SMB requests\&. By setting
fruit:encoding = native, all mapped characters are converted to native ASCII characters\&.
.PP
Finally, share access modes are optionally checked against Netatalk AFP sharing modes by setting
fruit:locking = netatalk\&.
.PP
This module is not stackable other then described in this manpage\&.
.SH "OPTIONS"
.PP
fruit:resource = [ file | xattr | stream ]
.RS 4
Controls where the OS X resource fork is stored:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file (default)
\- use a \&._ AppleDouble file compatible with OS X and Netatalk
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
xattr
\- use a xattr, requires a filesystem with large xattr support and a file IO API compatible with xattrs, this boils down to Solaris and derived platforms and ZFS
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
stream
\- pass the stream on to the next module in the VFS stack
.RE
.sp
.RE
.RE
.PP
fruit:metadata = [ stream | netatalk ]
.RS 4
Controls where the OS X metadata stream is stored:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
netatalk (default)
\- use Netatalk compatible xattr
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
stream
\- pass the stream on to the next module in the VFS stack
.RE
.sp
.RE
.RE
.PP
fruit:locking = [ netatalk | none ]
.RS 4

.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
none (default)
\- no cross protocol locking
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
netatalk
\- use cross protocol locking with Netatalk
.RE
.sp
.RE
.RE
.PP
fruit:encoding = [ native | private ]
.RS 4
Controls how the set of illegal NTFS ASCII character, commonly used by OS X clients, are stored in the filesystem:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
private (default)
\- store characters as encoded by the OS X client: mapped to the Unicode private range
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
native
\- store characters with their native ASCII value
.RE
.sp
.RE
.RE
.PP
fruit:aapl = yes | no
.RS 4
A global option whether to enable Apple\*(Aqs SMB2+ extension codenamed AAPL\&. Default
\fIyes\fR\&. This extension enhances several deficiencies when connecting from Macs:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
directory enumeration is enriched with Mac relevant filesystem metadata (UNIX mode, FinderInfo, resource fork size and effective permission), as a result the Mac client doesn\*(Aqt need to fetch this metadata individuallly per directory entry resulting in an often tremendous performance increase\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The ability to query and modify the UNIX mode of directory entries\&.
.RE
.sp
.RE
There\*(Aqs a set of per share options that can be used to disable the computation of specific Mac metadata in the directory enumeration context, all are enabled by default:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_rsize = true | false
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_finder_info = true | false
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
readdir_attr:aapl_max_access = true | false
.RE
.sp
.RE
.RE
.PP
fruit:nfs_aces = yes | no
.RS 4
Whether support for querying and modifying the UNIX mode of directory entries via NFS ACEs is enabled, default
\fIyes\fR\&.
.RE
.PP
fruit:veto_appledouble = yes | no
.RS 4
Whether \&._ AppleDouble files are vetoed which prevents the client from seing and accessing internal AppleDouble files created by vfs_fruit itself for the purpose of storing a Mac resource fork\&.
.sp
Vetoing \&._ files may break some applications, eg extracting Mac ZIP archives from Mac clients failes, because they contain \&._ files\&. Setting this option to false will fix this, but the abstraction leak of exposing the internally created \&._ files may have other unknown side effects\&.
.sp
The default is
\fIyes\fR\&.
.RE
.PP
fruit:copyfile = yes | no
.RS 4
Whether to enable OS X specific copychunk ioctl that requests a copy of a whole file along with all attached metadata\&.
.sp
WARNING: the copyfile request is blocking the client while the server does the copy\&.
.sp
\&.
	      The default is
\fIno\fR\&.
.RE
.PP
fruit:posix_rename = yes | no
.RS 4
Whether to enable POSIX directory rename behaviour for OS X clients\&. Without this, directories can\*(Aqt be renamed if any client has any file inside it (recursive!) open\&.
.sp
The default is
\fIyes\fR\&.
.RE
.SH "EXAMPLES"
.sp
.if n \{\
.RS 4
.\}
.nf
        \fI[share]\fR
	\m[blue]\fBea support = yes\fR\m[]
	\m[blue]\fBvfs objects = catia fruit streams_xattr\fR\m[]
	\m[blue]\fBfruit:resource = file\fR\m[]
	\m[blue]\fBfruit:metadata = netatalk\fR\m[]
	\m[blue]\fBfruit:locking = netatalk\fR\m[]
	\m[blue]\fBfruit:encoding = native\fR\m[]
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.PP
The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
